MacFormat 1995 March

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1995 March / macformat-022.iso / Shareware City / Utilities / MacDOS™ 2.0.0ƒ / User's Guide / 13.2 DIR - INCR < prev next >

Wrap

Text File | 1994-11-23 | 30.8 KB | 767 lines | [TEXT/ttxt]

DIR lists the contents of a folder (ie. a DIRectory). Syntax dir [selection] [/[-]A[[:]attribute list]] [/[-]B] [/C=creator] [/[-]L] [/[-]O[[:]ordering list]] [/[-]P] [/[- ]S] [/T=file type] [/[-]W] Parameters selection is a name preceded by an absolute or relative path which specifies the items to be listed. A group of files is identified via a wildcarded filename or a folder name. If selection is omitted, DIR lists the contents of the current folder. Switches /[-]A[[:]attribute list] only lists items with attributes included in the attribute list (but look at the note concerning DIRCMD). The attribute list is a string of single letter attributes: D for Directories, F for visible Files, H for Hidden files, X for aliases. A minus sign preceding an attribute tells MacDOS not to list items with that attribute. A minus sign between the / and the A inverts the logic of all attributes in the attribute list. By default, MacDOS does not list hidden files. /B lists item names one per line and without headings (bare format). When the /S option is also ON, /B writes the full path instead of the item name only. A minus sign between the / and the B switches this option OFF. /C=creator specifies that only files of a particular creator are to be listed. Note that no spaces are allowed on either side of the equal sign and that the creator string is four characters long. Therefore, if a creator includes spaces, you must double quote the switch (eg. dir \ "/c=ABC " lists all the files created by 'ABC ' in the root folder). /L operates case-sensitive matching on the selection. A minus sign between the / and the L switches this option OFF. [/[-]O[[:]ordering list]] sorts the items as specified in the ordering list before listing them. The ordering list is a string of single letter sorting criteria: D by Date & time of update (older first) G Group directories first N by Name (alphabetic) S by Size (smallest first) A minus sign preceding a sorting criterion tells MacDOS to sort in the reverse order. A minus sign between the / and the O inverts the logic of all criteria in the ordering list. /P pauses after each screenful of listing. A minus sign between the / and the P switches this option OFF. /S provides a recursive display of the items in all subfolders. A minus sign between the / and the S switches this option OFF. /T=file type specifies that only files of a particular type (eg. TEXT) are to be listed. Note that no spaces are allowed on either side of the equal sign and that the file type is four characters long. Therefore, if a file type includes spaces, you must double quote the switch (eg. dir \ "/t=ABC " lists all the files of type 'ABC ' in the root folder). /W lists item names in a wide format, with as many items per line as possible. A minus sign between the / and the W switches this option OFF. MacDOS vs DOS Switches The switches /AS, /AA, /AR, and /OE are not implemented, but /AF, /AX, /C, and /T have been introduced. Directory header To cope with the long names typical of the Mac, the path in the directory header is displayed with one directory name per line. Names containing spaces All names displayed are quoted, so that leading and trailing spaces are made visible. Use the system variable QUOTE to change the quoting character. Creators and File Types Creator and file-type are displayed. Listing of aliases Target volume and target filename of aliased items are displayed immediately after the directory entry for the alias file itself. Date and time formats Date and time are displayed in the format chosen by you (refer to the two commands DATE and TIME). Notes DIRCMD Before executing the command DIR, MacDOS selects the switches contained in the system variable DIRCMD. Therefore, DIRCMD represents the system default switches. You can override the defaults by explicitly including switches in the command (/-B negates /B, /W negates /-W, etc.). Alternatively, you can SET DIRCMD to your own preferred defaults. For instance, you can include /AH so that hidden files are always displayed. By including such a SET command in the autoexec.bat file, you only need to type your preferred defaults once. The system defaults are: /-P do not pause at the end of each page /-W do not list in wide format /A:-HDXF list directories, aliases, and files, but not hidden files /-O do not sort /-S list only the current folder (not recursively) /-B do not list in bare format /-L operate case-insensitive Repetition of switches in the same command Switches can be repeated. As MacDOS scans the switches from left to right, the rightmost switch of a particular type overrides the preceding ones. /A and /O can be repeated to extend their sub-option lists. For example, /A-H-D is totally equivalent to /A-H/A-D. Conflicting attributes in the attribute list MacDOS scans the attributes of the /A switch from left to right. Therefore, the rightmost attribute of a particular type takes effect. For example, /A:HDF-H does not display hidden files. If you type /-ADFH (or an equivalent sequence of attributes) you never get any item listed, because you exclude both folders and files (aliases are particular cases of files). Complex sorting MacDOS scans the ordering list from left to right. Therefore, the rightmost sorting is done last. For example, /O:SN first sorts by size, and then by name. Note that names are unique. Therefore, if you sort by name, all preceding sorts become totally irrelevant. A similar consideration also applies to /O:D, because the time of update is also almost always unique. The situation is different when you apply /ON or /OD before applying /OG or /OS. For example, if you apply /O:NSG, you list the directories ordered by name followed by the files ordered by size, with files of the same size in alphabetical order of their names. Sorting and recursion Each folder is sorted individually. Aliases Under normal circumstances, DIR displays two lines for each alias. The first line refers to the alias file itself, while the second line refers to the target. If the alias cannot be resolved (perhaps because the target is on a volume which has not been mounted), DIR reports a warning and then only displays the first line with an indication that the file is an alias. Note that when listing an alias, MacDOS always lists the corresponding targets, regardless of their type and visibility. Memory limitations DIR saves folder information in dynamically allocated memory rather than on disk. This speeds up the listing but limits the number of directory items which MacDOS can handle. With the current memory partition, this limit is of approximately 1100 entries. If MacDOS returns the error "Not enough space in the heap", the only solution (short of splitting the folder which is causing problems) is to increase the amount of memory allocated to MacDOS. To do so, exit MacDOS, click once on the application icon, press cmd-I, and increment the partition size. Examples dir lists the contents of the current folder. dir 2:/p lists the contents of the current folder of volume 2 and pauses at the end of each page. dir abc lists the file abc or the contents of the folder abc contained in the current folder dir ..\abc* lists all the items of the parent folder whose name begins with abc. dir \/w lists the contents of the root folder in a wide format. dir/t=TEXT/s recursively lists all text files in the current folder and in its subfolders dir \a\b\*TEMP*/L lists all the files in the folder \a\b whose name contains the string TEMP (case sensitive). dir/o-s/a-d lists the files (not the folders) in the current folder in order of size (from the largest to the smallest). dir \/s/b/c=ABCD/a-d lists all the files on the current volume created by ABCD. For each item, the full path and name is given. dir \t*/s/b/a-f lists all the folder names in the current volume which start with 't' or 'T'. dir/a-d-x/s/b>aFile \ saves into a file named aFile the list of all non-alias files in the current volume. For each item, the full path and name is given. dir /o-d/c=MWII lists all MacWrite II documents in order of update, from the newest to the oldest. dir 1:\/s/b/a-d-fh lists all hidden files on the startup volume. For each item, the full path and name is given. Frequently occurring errors E27: File or directory not found Perhaps you specified a proper filename (without wildcards) but the file does not exist. Alternatively, it is one of the folders within the path which does not exist. See Also TREE ECHO displays messages or turns batch command echoing ON and OFF. Syntax echo [{message | ON | OFF}] echo. Parameters {message | ON | OFF} is a string to be displayed in the MacDOS window. If the string only consists of the word ON, ECHO does not display it but enables the echoing of commands to the MacDOS window. Similarly, OFF causes the echoing to be disabled. If the parameter is entirely missing, ECHO displays the current echo setting (ON or OFF). ECHO immediately followed by a period (a dot) just displays an empty line. MacDOS vs DOS The two implementations are identical. Notes Interactive usage MacDOS lets you use ECHO interactively. Therefore, if you want to view a single global variable, type ECHO %var% rather than SET . Output redirection ECHO redirects its output when you include it in a batch program and redirect the output of the whole batch. EJECT dismounts and places off-line removable volumes. Syntax eject volume [/E] Parameters volume is the ID which identifies the volume to be dismounted or placed off-line. Without switches, EJECT dismounts the volume. Switches /E specifies that the volume is only to be placed off-line (eg. Ejected) without being dismounted. MacDOS vs DOS DOS does not support EJECT. Notes The start-up volume cannot be dismounted regardless of whether it is removable or not. Examples eject 2: removes the volume with ID 2. The icon disappears from the desktop. eject D /e ejects the volume D. The icon is then greyed. EXIT quits MacDOS, other applications, or the Finder. Syntax exit [appl] exit finder Parameters appl identifies the application that should receive a Quit Apple Event. If the parameter is missing, MacDOS terminates itself. MacDOS vs DOS In DOS, EXIT is used to quit the current shell and possibly return to a program which was suspended. Notes EXIT's main purpose is to use batch programs as stand-alone applications which automatically terminate after completing their task. Quitting the Finder When you kill the Finder, you no longer have access to the items normally in the Apple menu. Be warned that MacDOS relies on the 'MACS' creator to identify the process associated with the Finder. If you have already replaced the Finder with a different application, the "exit finder" command will have no effect. You can re-launch the Finder by typing its path/filename as if it were a normal application. Make an alias of the Finder, name it F, and place it in a folder included in the search PATH. You will then be able to then re-launch the Finder with just two key strokes. FOR executes a command or a series of commands for each file in a set. Syntax for %var [/L] in (set) do [command | begin] Parameters var is the name of the variable that FOR uses to store the names of the files in set, one at a time. When you use the format "do command", type the string %var where you would normally type a filename. FOR then executes the command for all files in the set, one at a time. When you use the format "do begin", var becomes a global variable rather than a variable local to FOR. Therefore, type %var% to obtain the name of the current file. set is a list of space-separated items, where each item is either a file or a folder name. Each item can be preceded by a volume and path spec, and filenames can be wildcarded. The parentheses are mandatory. command | begin is either the single command to be executed or a keyword which starts the execution of a series of command lines. With begin, MacDOS keeps executing command lines until it encounters a line containing the command NEXT var . At that point, MacDOS sets var to the next filename in the set and resumes execution from the line immediately following the begin. After 'using' all the files in set, MacDOS continues execution of the batch program from the line immediately following the NEXT. Switches /L leaves the filenames in the set as they are, without converting them to uppercase. The default is that the filenames are converted. This switch must precede the do. MacDOS vs DOS Multi-line FORs The keyword begin allows for loops spanning over more than one line. De-referencing the loop control variable With standard single-line FORs, the control variable is always de-referenced by prepending a single percent sign (as in %varName), regardless of whether the FOR is in a batch program or not. DOS needs a double percent sign in batch programs. With multi-line loops, the control variable becomes a standard global variable and is de-referenced normally (as in %varName%). Lower case option DOS does not support /L. What can be done Beside normal commands, MacDOS also accepts program names and the command CALL after the do. Folder expansion Folder names in a set are expanded, so that (folderName) in MacDOS is equivalent to (folderName\*.*) in DOS. This seems more consistent with the way in which folder names are usually handled by file-oriented commands. Notes Replacing FOR FOR is a command which has mainly been implemented to help experienced DOS users. Although it has been extended in a series of ways, its use remains limited because it does not distinguish between file types, does not return full paths, and does not operate recursively. The most flexible way of operating on a set of files with MacDOS is to use the following strategy: • redirect the output of DIR/B to a file (all the filtering options of DIR as well as its recursive operation are available); • OPEN the file; • repeat the READing of the file, so that a filename at a time is stored in a global variable and is available for processing; • CLOSE the file (only if you do not reach the EOF, otherwise MacDOS closes the file automatically); • reSET the global variables used and DELete the file (always clean-up the mess before you start doing something else). Interactive vs. batch You can execute the standard FOR interactively, while you can only use the multi-line FOR within batch programs. What happens to the control variable after exiting the FOR loop The control variable of standard single-line FORs is a local variable and is not accessible within other commands. On the other hand, the control variable of multi-line FORs is a normal global variable. After terminating the loop, such a variable contains the name of the last file in the set and it is your responsibility to remove it by SETting it to the empty string. To remove it immediately after exiting the loop is a good defensive practice. I/O redirection Redirection is only legal with the standard single-line format of FOR. In that case, it applies to the command which follows the do rather than to the FOR itself. Piping of the output to other commands is forbidden except to MORE. To put it simply, FOR only supports piping in the following case: FOR %var [/L] IN (set) DO internal-com-with-params | MORE Incompatibility of commands Standard FORs cannot be nested. That is, no FOR command is allowed after the do keyword of another FOR. IFs are also forbidden within standard FORs. Empty set If the set does not select any file, FORs do not return any error and multi-line FORs do not create the global variable. Running away If a command within a FOR generates a file which belongs to the set, a situation in which the loop "feeds" itself with new files can occur. Such a "runaway" condition would only stop upon hitting some system boundaries. Here are a couple of examples: for %var in (d*) do dir/b > %varX this command generates a file for each file whose name begins with the letter 'd'. Unfortunately, the new file also begins with 'd' and is therefore part of the set. To see what happens, let's say that you have a file named DATA. In the first iteration of the FOR-loop, MacDOS generates DATAX; in the second iteration DATAXX; then DATAXXX; etc. This only stops when the maximum length of filenames (31 characters) is reached. If you had named the new files X%var instead of %varX, you would have been fine. set counter=0 for %var in (*t*) do begin incr counter copy %var% data%counter% next var here the purpose was to make copies of all files containing the letter 't' and name them data1, data2, etc. Again, the problem is that the new files are in the set. New files are probably created until the hard disk is full. You could have named the new files xxx%counter% and then renamed them with ren xxx* data* at a later stage. Alternatively, you could have stored the copies into a different folder. The general solution is to replace FOR with a combination of DIR and a loop. This would avoid the risk of "positive feedback". Examples for %a in (wildcardedFilename) do more < %a executes a MORE on all files identified by wildcardedFilename (it only works with files in the current folder and if they are of type 'TEXT'). for %a in (myDir) do more < myDir\%a executes a MORE on all files in the folder myDir (it only works if the files are of type 'TEXT'). Frequently occurring errors E27: File or directory not found At least one of the paths specified in the set included a folder which does not exist. See Also NEXT GOTO while in batch, continues execution from a labelled line. Syntax goto label Parameters label is an alphanumeric string used as a label in the current batch program. Remember that the colon which identifies the label is not part of the label itself. MacDOS vs DOS The two implementations are identical. Examples goto QUIT_LBL goto 4 GOTO lbl10 goto %var% Frequently occurring errors E44: Label not found The requested label was not defined in the current batch program. HELP provides on-line information for all MacDOS commands. Syntax help [entry] Parameters entry is either a command name, a file specification, or a question mark. When entry is a command name, HELP displays a description of the command. When entry identifies a file, HELP searches the resource fork of the file looking for a resource of type 'TEXT' named "help". If it finds it, it display its contents in the console window. This lets you get help on any program, filter, and script provided it contains the appropriate 'TEXT' resource. When entry is a question mark, HELP lists all the command names. If entry is missing, HELP lists brief descriptions of all the commands. MacDOS vs DOS The two implementations are identical, except for the fact that MacDOS supports "HELP ?" and can read "help" text resources. IF performs conditional processing in batch. Syntax if [not] {s1 == s1 | exist name | existdir name} command Parameters {s1 == s1 | exist name | existdir name} is a condition which can have three forms: s1 == s1 is true when the two strings s1 and s2 are identical. The two strings can contain replaceable parameters and global variables. exist name is true when a file named name exists. The actual filename can be preceded by a volume specification and path. existdir name is true when a folder named name exists. The actual folder name can be preceded by a volume specification and path. A not preceding a condition changes a true condition to false and vice versa. command is executed when the condition is true. It can be a MacDOS command or the name of an executable program. MacDOS vs DOS Keywords DOS does not support existdir; MacDOS does not support errorlevel. Hidden files Hidden files exist for MacDOS but not for DOS. Notes Aliases When the item tested with exist or existdir includes a path, MacDOS resolves all the aliases of folders in the path but not the innermost one. Therefore, aliases always satisfy exist and never existdir, regardless of whether the target is a file or a folder. Incompatibility with FOR IFs are not allowed within standard FORs. That is, you cannot type: for %var in (set) do if %var == ... The solution is to use multi-line FORs (or to drop FORs altogether). Note that you can execute a FOR within an IF. Reserved words The words not, exist, and existdir are reserved in both upper and lower case. Therefore, commands like if not == %var% are in most cases rejected with a syntax error. Here is an example in which IF might not do what you expect: if not exist == %1 do_this The purpose is probably to execute do_this if the first replaceable parameter contains the string "exist". Unfortunately, IF interprets the command line as a request to execute "%1 do_this" if a file named "==" does not exist. Most likely, you do not have such a file. Therefore, MacDOS will attempt to execute "%1 do_this". This can be very confusing, especially when you have ECHO disabled. To avoid this kind of problems, you have the following choices: • Never use reserved words (preferred solution). • Double-quote reserved words and variables which could contain reserved words: if "%var%" == "not" do_this if not "exist" == %1 do_this Spaces Spaces within a condition are ignored, unless you double- quote them. Also, strings containing spaces must be double quoted. Examples Check the existence of a file: if exist %1 echo file "%1" exists Check the non-existence of a folder: if not existdir %1 echo folder "%1" not there Use a batch program to process all files in a folder, but only after checking that the folder exists: if existdir %1 for %file in (%1) do processFile %1\%file Check the control variable of a loop: if %counter% == 7 goto EXIT_LOOP_LBL Check an error condition: if not %doserr% == 0 goto ERROR_LBL Frequently occurring errors E13: Syntax: invalid arguments Very often this error message is caused by a reference to a replaceable parameter which was not defined. For example, if %1 == 3 do_this fails if %1 is empty. It is so because MacDOS, after replacing %1, only sees if == 3 do_this and cannot make any sense of it. To avoid this problem, append a character to both sides of the condition (a space does not work unless you use double quotes): if %1x == 3x do_this . Then MacDOS sees if x == 3x do_this and behaves as expected. INCR increments or extends values of global variables. Syntax incr [+ | -]var [by {number | string}] "incr var", equivalent to "incr +var by 1", increments by 1 numeric values and appends one space to the end of alphanumeric strings. Parameters [+ | -]var is the name of a global variable, possibly preceded by a plus or a minus sign. No space is allowed between the sign and the variable name. INCR uses the sign to decide whether to perform string operations at the end or at the beginning of var's value. number is a signed integer number. INCR uses number differently depending on whether var contains a numeric value or not: • When var contains a numeric value, INCR replaces it with the value obtained after adding number. • When var contains an alphanumeric string which cannot be interpreted as a number, INCR extends it by adding number spaces. The characters are inserted before the beginning if the variable name is preceded by the minus sign, otherwise they are appended after its end. When number is negative, INCR actually shortens the content of var by removing characters from the end or from the beginning (depending on the presence of the minus sign before the variable name). string is an alphanumeric string which cannot be interpreted as a number. INCR joins string to the string contained in var. The string is prepended if the variable name is preceded by the minus sign, otherwise the string is appended. MacDOS vs DOS DOS does not support INCR. Notes Appending numeric characters When the BY-string is numeric, INCR increments a numeric variable by that amount or adds that number of spaces to an alphanumeric variable. If your purpose is to add digits to a variable (eg. appending '1' to the string "134" so that it becomes "1341"), you can achieve this result by extending the BY-string with an alphabetic character and then immediately removing it from the variable (ie. INCR var BY 1x followed by DECR var BY x). Examples initial var command resulting var "25" incr var "26" "25" incr -var "26" "-25" incr var by 30 "5" "25" incr var by -3 "22" "-7" incr var by -30 "-37" "abcde" incr var "abcde " "abcde" incr -var " abcde" "abcde" incr var by 3 "abcde " "abcde" incr var by -1 "abcd" "abcde" incr -var by -3 "de" "ab de" incr var by de "ab dede" "a cde" incr -var by "a " "a a cde" "abcde" incr +var by -7 var removed Frequently occurring errors E63: Requested variable has not been defined You attempted to INCRement a variable that did not exist. Remember that empty variables are automatically removed unless they are system variables. See Also DECR, SSTR, TOUPPER